home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / g_man / cat3 / ftn / stenci.z / stenci
Encoding:
Text File  |  2002-10-03  |  9.2 KB  |  199 lines
  1.  
  2.  
  3.  
  4. sssstttteeeennnncccciiii((((3333GGGG))))                                                          sssstttteeeennnncccciiii((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      sssstttteeeennnncccciiii - alter the operating parameters of the stencil
  10.  
  11. FFFFOOOORRRRTTTTRRRRAAAANNNN SSSSPPPPEEEECCCCIIIIFFFFIIIICCCCAAAATTTTIIIIOOOONNNN
  12.      ssssuuuubbbbrrrroooouuuuttttiiiinnnneeee sssstttteeeennnncccciiii((((eeeennnnaaaabbbblllleeee,,,, rrrreeeeffff,,,, ffffuuuunnnncccc,,,, mmmmaaaasssskkkk,,,, ffffaaaaiiiillll,,,, ppppaaaassssssss,,,, zzzzppppaaaassssssss))))
  13.      iiiinnnntttteeeeggggeeeerrrr****4444 eeeennnnaaaabbbblllleeee,,,, rrrreeeeffff,,,, ffffuuuunnnncccc,,,, mmmmaaaasssskkkk,,,, ffffaaaaiiiillll,,,, ppppaaaassssssss,,,, zzzzppppaaaassssssss
  14.  
  15. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  16.      _e_n_a_b_l_e   expects either  ....TTTTRRRRUUUUEEEE.... or  ....FFFFAAAALLLLSSSSEEEE...., enabling or disabling
  17.               stencil operation.  When stencil operation is disabled (the
  18.               default), the values of the subsequent six parameters are
  19.               ignored,
  20.  
  21.      _r_e_f      expects a reference value used by the stencil compare function.
  22.  
  23.      _f_u_n_c     expects one of eight flags specifying the stencil comparison
  24.               function.  These flags are SSSSFFFFNNNNEEEEVVVVEEEE, SSSSFFFFLLLLEEEESSSSSSSS, SSSSFFFFEEEEQQQQUUUUAAAA, SSSSFFFFLLLLEEEEQQQQUUUU,
  25.               SSSSFFFFGGGGRRRREEEEAAAA, SSSSFFFFNNNNOOOOTTTTEEEE, SSSSFFFFGGGGEEEEQQQQUUUU, and SSSSFFFFAAAALLLLWWWWAAAA.
  26.  
  27.      _m_a_s_k     expects a mask specifying which stencil bitplanes are
  28.               significant during the comparison operation.
  29.  
  30.      _f_a_i_l     expects one of six flags indicating which stencil operation
  31.               should be performed should the stencil test fail.  The values
  32.               are SSSSTTTTKKKKEEEEEEEEPPPP, SSSSTTTTZZZZEEEERRRROOOO, SSSSTTTTRRRREEEEPPPPLLLL, SSSSTTTTIIIINNNNCCCCRRRR, SSSSTTTTDDDDEEEECCCCRRRR, and SSSSTTTTIIIINNNNVVVVEEEE.
  33.  
  34.      _p_a_s_s     expects one of six flags indicating which stencil operation
  35.               should be performed should the stencil test pass, and the z-
  36.               buffer test (if z-buffering is enabled) fail.  The values are
  37.               SSSSTTTTKKKKEEEEEEEEPPPP, SSSSTTTTZZZZEEEERRRROOOO, SSSSTTTTRRRREEEEPPPPLLLL, SSSSTTTTIIIINNNNCCCCRRRR, SSSSTTTTDDDDEEEECCCCRRRR, and SSSSTTTTIIIINNNNVVVVEEEE.
  38.  
  39.      _z_p_a_s_s    expects one of six flags indicating which stencil operation
  40.               should be performed should the stencil and z-buffer tests pass.
  41.               Its value is not significant when the z-buffer is not enabled.
  42.               The values are SSSSTTTTKKKKEEEEEEEEPPPP, SSSSTTTTZZZZEEEERRRROOOO, SSSSTTTTRRRREEEEPPPPLLLL, SSSSTTTTIIIINNNNCCCCRRRR, SSSSTTTTDDDDEEEECCCCRRRR, and
  43.               SSSSTTTTIIIINNNNVVVVEEEE.
  44.  
  45. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  46.      sssstttteeeennnncccciiii operates as a superior z-buffer test with a different algorithm.
  47.      When sssstttteeeennnncccciiii is enabled, each pixel write first tests the stencil
  48.      bitplanes.  Both the color and z-buffer bitplane writes, as well as the
  49.      write of the stencil bitplanes, are conditioned by the stencil test.
  50.      sssstttteeeennnncccciiii operation can be enabled only if stencil bitplanes are present
  51.      (see sssstttteeeennnnssssiiii).  Stencil bitplanes are present only in the normal
  52.      framebuffer, so sssstttteeeennnncccciiii should be called only while draw mode is NNNNOOOORRRRMMMMAAAALLLL.
  53.  
  54.      When the z-buffer is enabled, three test cases are distinguished:
  55.  
  56.      _f_a_i_l     Stencil test fails.
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. sssstttteeeennnncccciiii((((3333GGGG))))                                                          sssstttteeeennnncccciiii((((3333GGGG))))
  71.  
  72.  
  73.  
  74.      _p_a_s_s     Stencil test passes, but z-buffer test fails.
  75.  
  76.      _z_p_a_s_s    Stencil test passes, and z-buffer test passes.
  77.  
  78.      (When the z-buffer is not enabled, only cases _f_a_i_l and _p_a_s_s are
  79.      considered.)  In all three cases the stencil bitplanes are updated with a
  80.      potentially new value.  This value is a function of the case.  The user
  81.      specifies, for each case, which of six possible values will be used:
  82.  
  83.      SSSSTTTTKKKKEEEEEEEEPPPP     Keep the current value (no change).
  84.  
  85.      SSSSTTTTZZZZEEEERRRROOOO     Replace with zero.
  86.  
  87.      SSSSTTTTRRRREEEEPPPPLLLL     Replace with the reference value.
  88.  
  89.      SSSSTTTTIIIINNNNCCCCRRRR     Increment by one (clamp to max).
  90.  
  91.      SSSSTTTTDDDDEEEECCCCRRRR     Decrement by one (clamp to zero).
  92.  
  93.      SSSSTTTTIIIINNNNVVVVEEEE     Invert all bits.
  94.  
  95.      Arguments _f_a_i_l, _p_a_s_s, and _z_p_a_s_s are each specified as one of SSSSTTTTKKKKEEEEEEEEPPPP,
  96.      SSSSTTTTZZZZEEEERRRROOOO, SSSSTTTTRRRREEEEPPPPLLLL, SSSSTTTTIIIINNNNCCCCRRRR, SSSSTTTTDDDDEEEECCCCRRRR, and SSSSTTTTIIIINNNNVVVVEEEE.
  97.  
  98.      _r_e_f is the reference value used by the function that determines whether
  99.      the stencil test passes or fails.  _f_u_n_c specifies the comparison between
  100.      ref and the current stencil plane value.  This comparison function is
  101.      specified with the flags:
  102.  
  103.      SSSSFFFFNNNNEEEEVVVVEEEE     Never pass.
  104.  
  105.      SSSSFFFFLLLLEEEESSSSSSSS     Pass if _r_e_f is less than _s_t_e_n_c_i_l.
  106.  
  107.      SSSSFFFFLLLLEEEEQQQQUUUU     Pass if _r_e_f is less than or equal to _s_t_e_n_c_i_l.
  108.  
  109.      SSSSFFFFEEEEQQQQUUUUAAAA     Pass if _r_e_f is equal to _s_t_e_n_c_i_l.
  110.  
  111.      SSSSFFFFGGGGRRRREEEEAAAA     Pass if _r_e_f is greater than _s_t_e_n_c_i_l.
  112.  
  113.      SSSSFFFFGGGGEEEEQQQQUUUU     Pass if _r_e_f is greater than or equal to _s_t_e_n_c_i_l.
  114.  
  115.      SSSSFFFFNNNNOOOOTTTTEEEE     Pass if _r_e_f is not equal to _s_t_e_n_c_i_l.
  116.  
  117.      SSSSFFFFAAAALLLLWWWWAAAA     Always pass.
  118.  
  119.      The stencil bitplanes are treated as an unsigned integer of _p_l_a_n_e_s bits,
  120.      where _p_l_a_n_e_s is the value passed to sssstttteeeennnnssssiiii to allocate the stencil
  121.      buffer.
  122.  
  123.      _m_a_s_k is a field that specifies which stencil bitplanes are to be
  124.      considered by the test.  It does not affect which bitplanes are updated.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. sssstttteeeennnncccciiii((((3333GGGG))))                                                          sssstttteeeennnncccciiii((((3333GGGG))))
  137.  
  138.  
  139.  
  140.      If the z-buffer is enabled, color and depth fields are drawn only in the
  141.      _z_p_a_s_s case (both the stencil and depth tests pass).  If the z-buffer is
  142.      not enabled, color is drawn only in the _p_a_s_s case.  The _z_p_a_s_s case is
  143.      ignored.
  144.  
  145. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  146.      drawmo, polymo, sclear, stensi, swrite, zbuffe
  147.  
  148. NNNNOOOOTTTTEEEESSSS
  149.      IRIS-4D G, GT, and GTX models, as well as the Personal Iris, Iris Indy,
  150.      Iris Indigo Entry, and Indigo XL, do not support sssstttteeeennnncccciiii.  Use ggggeeeettttggggddddeeee to
  151.      determine whether sssstttteeeennnncccciiii is supported.
  152.  
  153.      sssstttteeeennnncccciiii is supported only in the normal framebuffer, and is therefore
  154.      effective only while draw mode is NNNNOOOORRRRMMMMAAAALLLLWWWW.
  155.  
  156. BBBBUUUUGGGGSSSS
  157.      IRIS-4D VGX models do not support stencil operation when aaaaffffuuuunnnncccctttt is
  158.      enabled.
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.